事件推送

注册回调即可实时接收机器人事件报警，新增集团客户推送支持。

• 兼容性：2025‑05‑15（含）之后新建或重新保存的订阅将采用本文描述的 新顶级字段格式。
• 已生效的旧订阅保持两级结构（appId + payload），功能不受影响。
• 新顶级字段（与 appId、payload 同级）。

接入流程

第一步：配置回调地址

1. 登录开发者中心，进入 企业回调地址。页面分为「事件回调地址」与「任务报告回调地址」两块，本页只涉及第一块。
2. 指定 推送账号：该账号必须是本客户的开发者，也是唯一能修改本页的人。推送范围由它决定——只有直接绑定到该推送账号的机器人，其事件才会推送；仅归属本客户但未直接绑定给该账号的机器人不会推送。事件与任务共用同一个推送账号。
3. 点击「事件回调地址」区块的 修改，填写回调 url 与事件语言，打开推送开关后点击 保存。
4. 保存后平台签发该订阅的 AppId 与 Secret，在「回调凭证 / 管理凭证」中查看。Secret 只在重置后可再次查看，请当场保存。

第二步：实现验签

推送会携带 X-Gausium-App-Id、X-Gausium-Timestamp、X-Gausium-Nonce、X-Gausium-Signature 四个请求头。请先完成验签再解析 body，具体算法与中英文示例见回调验签。

第三步：联调

点击区块内的 测试，平台会向填写的地址 POST 一次 payload.test = true 的探测包。返回 2xx 且验签通过，说明链路已通。

第四步：接收并处理推送

链路打通后即可按下方字段表解析事件。业务处理中的常见判断（报警与恢复如何配对、哪些等级会推送、推送丢失如何兜底）见怎么判断某个故障已经恢复与哪些等级的告警会被推送。

请在接收侧落库

V3 目前只提供事件推送，没有事件查询接口。推送丢失后无法补拉，请把接收到的推送落库保存，作为事件历史的唯一来源。

回调注册要求

1. 语言：符合 IETF BCP 47（如 en-US、zh-CN）。

2. 回调：

   • url 例如 https://{{host}}/callback，HTTP 方法 POST。
   • appId 例如 24416c36-d9c7-4d74-a047-d6ca461fxxxx（用于鉴权。由高仙签发后提供）。

示例（新格式）

curl -X POST "https://{{host}}/callback" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "24416c36-d9c7-4d74-a047-d6ca461fxxxx",
    "payload": {
      "serialNumber": "ITEST00-0000-000-XXXX",
      "modelTypeCode": "Scrubber 50H",
      "content": {
        "incidentCode": "20005",
        "incidentName": "污水箱已满，请排污水",
        "incidentLevel": "H2",
        "incidentId": "d3919667-a9ce-463e-8d3e-4203c89bddcx",
        "incidentStatus": 1,
        "startTime": "2026-03-26T00:17:25Z",
        "endTime": "",
        "taskId": null,
        "subTaskId": null,
        "taskInstanceId": "",
        "taskName": "地面清洁",
        "mapId": "fc8101e8-626a-4a32-9ee6-c63d9871290x",
        "mapName": "大厦二层",
        "navInstanceId": null,
        "navName": null
    }
}'

顶级字段说明

字段	类型	描述
appId	String	用于鉴权，保持不变
payload	Object	业务数据，结构与旧版保持一致

参数描述：

字段名称	字段类型	字段描述	示例
payload.serialNumber	String	机器人序列号	"TEST00-0000-000-XXXX"
payload.modelTypeCode	String	机器人型号代码	"Scrubber 50H"
payload.content	Object	事件内容
payload.content.incidentCode	String	事件代码	"1011"
payload.content.incidentName	String	事件名称	"Clean water full"
payload.content.incidentLevel	String	事件等级	"H2"
payload.content.incidentId	String	事件ID	"c084a905-597e-4085-90dd-ecab697dxxxx"
payload.content.incidentStatus	int	事件状态，1 报警，0 恢复	1
payload.content.startTime	String	事件开始时间，UTC时间	"2023-01-14T02:09:28Z"
payload.content.endTime	String	事件结束时间，UTC时间。如果事件未恢复，结束时间为空字符串	"2023-01-14T02:09:28Z" 或 ""
payload.content.taskId	String	事件发生时，机器人正在执行的任务id	"c084a905-597e-4085-90dd-ecab697dxxxx"
payload.content.subTaskId	String	事件发生时，机器人正在执行的子任务id	"c084a905-597e-4085-90dd-ecab697dxxxx"
payload.content.taskInstanceId	String	事件发生时，机器人正在执行的任务实例id	"c084a905-597e-4085-90dd-ecab697dxxxx"
payload.content.taskName	String	事件发生时，机器人正在执行的任务名称	"task1"
payload.content.mapId	String	事件发生时，机器人所在地图的id	"c084a905-597e-4085-90dd-ecab697dxxxx"
payload.content.mapName	String	事件发生时，机器人所在的地图名称	"map1"
payload.content.navInstanceId	String	事件发生时，机器人正在执行的导航实例id	"da4b1ca9-dbfe-4dd2-bcbe-715c00904f0b"
payload.content.navName	String	事件发生时，机器人正在执行的导航点名称	"hop"
payload.content.incidentLevel：

值	名称	描述
H0	事件	这不是报警，仅是事件通知
H1	状态	埋点统计
H2	状态	机器人的常规状态，用户无需指导即可解决
H3	警告	不影响机器人任务，用户可以解决
H4	协助，问题	影响机器人任务，用户可以解决
H5	隐患	不影响机器人任务，用户无法解决
H6	故障	影响机器人任务，用户无法解决
H7	质量问题	严重故障